9.3 Sequence Functions

This section describes a number of Common Lisp functions for operating on sequences.

Function: cl-subseq sequence start &optional end

This function returns a given subsequence of the argument sequence, which may be a list, string, or vector. The indices start and end must be in range, and start must be no greater than end. If end is omitted, it defaults to the length of the sequence. The return value is always a copy; it does not share structure with sequence.

As an extension to Common Lisp, start and/or end may be negative, in which case they represent a distance back from the end of the sequence. This is for compatibility with Emacs’s substring function. Note that cl-subseq is the only sequence function that allows negative start and end.

You can use setf on a cl-subseq form to replace a specified range of elements with elements from another sequence. The replacement is done as if by cl-replace, described below.

Function: cl-concatenate result-type &rest seqs

This function concatenates the argument sequences together to form a result sequence of type result-type, one of the symbols vector, string, or list. The arguments are always copied, even in cases such as (cl-concatenate 'list '(1 2 3)) where the result is identical to an argument.

Function: cl-fill seq item &key :start :end

This function fills the elements of the sequence (or the specified part of the sequence) with the value item.

Function: cl-replace seq1 seq2 &key :start1 :end1 :start2 :end2

This function copies part of seq2 into part of seq1. The sequence seq1 is not stretched or resized; the amount of data copied is simply the shorter of the source and destination (sub)sequences. The function returns seq1.

If seq1 and seq2 are eq, then the replacement will work correctly even if the regions indicated by the start and end arguments overlap. However, if seq1 and seq2 are lists that share storage but are not eq, and the start and end arguments specify overlapping regions, the effect is undefined.

Function: cl-remove item seq &key :test :test-not :key :count :start :end :from-end

This returns a copy of seq with all elements matching item removed. The result may share storage with or be eq to seq in some circumstances, but the original seq will not be modified. The :test, :test-not, and :key arguments define the matching test that is used; by default, elements eql to item are removed. The :count argument specifies the maximum number of matching elements that can be removed (only the leftmost count matches are removed). The :start and :end arguments specify a region in seq in which elements will be removed; elements outside that region are not matched or removed. The :from-end argument, if true, says that elements should be deleted from the end of the sequence rather than the beginning (this matters only if count was also specified).

Function: cl-delete item seq &key :test :test-not :key :count :start :end :from-end

This deletes all elements of seq that match item. It is a destructive operation. Since Emacs Lisp does not support stretchable strings or vectors, this is the same as cl-remove for those sequence types. On lists, cl-remove will copy the list if necessary to preserve the original list, whereas cl-delete will splice out parts of the argument list. Compare append and nconc, which are analogous non-destructive and destructive list operations in Emacs Lisp.

The predicate-oriented functions cl-remove-if, cl-remove-if-not, cl-delete-if, and cl-delete-if-not are defined similarly.

Function: cl-remove-duplicates seq &key :test :test-not :key :start :end :from-end

This function returns a copy of seq with duplicate elements removed. Specifically, if two elements from the sequence match according to the :test, :test-not, and :key arguments, only the rightmost one is retained. If :from-end is true, the leftmost one is retained instead. If :start or :end is specified, only elements within that subsequence are examined or removed.

Function: cl-delete-duplicates seq &key :test :test-not :key :start :end :from-end

This function deletes duplicate elements from seq. It is a destructive version of cl-remove-duplicates.

Function: cl-substitute new old seq &key :test :test-not :key :count :start :end :from-end

This function returns a copy of seq, with all elements matching old replaced with new. The :count, :start, :end, and :from-end arguments may be used to limit the number of substitutions made.

Function: cl-nsubstitute new old seq &key :test :test-not :key :count :start :end :from-end

This is a destructive version of cl-substitute; it performs the substitution using setcar or aset rather than by returning a changed copy of the sequence.

The functions cl-substitute-if, cl-substitute-if-not, cl-nsubstitute-if, and cl-nsubstitute-if-not are defined similarly. For these, a predicate is given in place of the old argument.